   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2) v3.2, April, May 1997

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

Fonts
=====

   This section describes how to work with font specifier and font
instance objects, which encapsulate fonts in the window system.

Font Specifiers
---------------

 - Function: font-specifier-p OBJECT
     This predicate returns `t' if OBJECT is a font specifier, and
     `nil' otherwise.

Font Instances
--------------

 - Function: font-instance-p OBJECT
     This predicate returns `t' if OBJECT is a font instance, and `nil'
     otherwise.

 - Function: make-font-instance NAME &optional DEVICE NOERROR
     This function creates a new font-instance object of the specified
     name.  DEVICE specifies the device this object applies to and
     defaults to the selected device.  An error is signalled if the
     font is unknown or cannot be allocated; however, if NOERROR is
     non-`nil', `nil' is simply returned in this case.

     The returned object is a normal, first-class lisp object.  The way
     you "deallocate" the font is the way you deallocate any other lisp
     object: you drop all pointers to it and allow it to be garbage
     collected.  When these objects are GCed, the underlying X data is
     deallocated as well.

Font Instance Names
-------------------

 - Function: list-fonts PATTERN &optional DEVICE
     This function returns a list of font names matching the given
     pattern.  DEVICE specifies which device to search for names, and
     defaults to the currently selected device.

 - Function: font-instance-name FONT-INSTANCE
     This function returns the name used to allocate FONT-INSTANCE.

 - Function: font-instance-truename FONT-INSTANCE
     This function returns the canonical name of the given font
     instance.  Font names are patterns which may match any number of
     fonts, of which the first found is used.  This returns an
     unambiguous name for that font (but not necessarily its only
     unambiguous name).

Font Instance Size
------------------

 - Function: x-font-size FONT
     This function returns the nominal size of the given font.  This is
     done by parsing its name, so it's likely to lose.  X fonts can be
     specified (by the user) in either pixels or 10ths of points, and
     this returns the first one it finds, so you have to decide which
     units the returned value is measured in yourself ...

 - Function: x-find-larger-font FONT &optional DEVICE
     This function loads a new, slightly larger version of the given
     font (or font name).  Returns the font if it succeeds, `nil'
     otherwise.  If scalable fonts are available, this returns a font
     which is 1 point larger.  Otherwise, it returns the next larger
     version of this font that is defined.

 - Function: x-find-smaller-font FONT &optional DEVICE
     This function loads a new, slightly smaller version of the given
     font (or font name).  Returns the font if it succeeds, `nil'
     otherwise.  If scalable fonts are available, this returns a font
     which is 1 point smaller.  Otherwise, it returns the next smaller
     version of this font that is defined.

Font Instance Characteristics
-----------------------------

 - Function: font-instance-properties FONT
     This function returns the properties (an alist or `nil') of
     FONT-INSTANCE.

 - Function: x-make-font-bold FONT &optional DEVICE
     Given an X font specification, this attempts to make a "bold" font.
     If it fails, it returns `nil'.

 - Function: x-make-font-unbold FONT &optional DEVICE
     Given an X font specification, this attempts to make a non-bold
     font.  If it fails, it returns `nil'.

 - Function: x-make-font-italic FONT &optional DEVICE
     Given an X font specification, this attempts to make an "italic"
     font.  If it fails, it returns `nil'.

 - Function: x-make-font-unitalic FONT &optional DEVICE
     Given an X font specification, this attempts to make a non-italic
     font.  If it fails, it returns `nil'.

 - Function: x-make-font-bold-italic FONT &optional DEVICE
     Given an X font specification, this attempts to make a
     "bold-italic" font.  If it fails, it returns `nil'.

Font Convenience Functions
--------------------------

 - Function: font-name FONT &optional DOMAIN
     This function returns the name of the FONT in the specified
     DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
     is normally a window and defaults to the selected window if
     omitted.  This is equivalent to using `specifier-instance' and
     applying `font-instance-name' to the result.

 - Function: font-truename FONT &optional DOMAIN
     This function returns the truename of the FONT in the specified
     DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
     is normally a window and defaults to the selected window if
     omitted.  This is equivalent to using `specifier-instance' and
     applying `font-instance-truename' to the result.

 - Function: font-properties FONT &optional DOMAIN
     This function returns the properties of the FONT in the specified
     DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
     is normally a window and defaults to the selected window if
     omitted.  This is equivalent to using `specifier-instance' and
     applying `font-instance-properties' to the result.

Colors
======

Color Specifiers
----------------

 - Function: color-specifier-p OBJECT
     This function returns non-`nil' if OBJECT is a color specifier.

Color Instances
---------------

   A "color-instance object" is an object describing the way a color
specifier is instanced in a particular domain.  Functions such as
`face-background-instance' return a color-instance object.  For example,

     (face-background-instance 'default (next-window))
         => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>

   The color-instance object returned describes the way the background
color of the `default' face is displayed in the next window after the
selected one.

 - Function: color-instance-p OBJECT
     This function returns non-`nil' if OBJECT is a color-instance.

Color Instance Properties
-------------------------

 - Function: color-instance-name COLOR-INSTANCE
     This function returns the name used to allocate COLOR-INSTANCE.

 - Function: color-instance-rgb-components COLOR-INSTANCE
     This function returns a three element list containing the red,
     green, and blue color components of COLOR-INSTANCE.

          (color-instance-rgb-components
            (face-background-instance 'default (next-window)))
              => (65535 58596 46517)

Color Convenience Functions
---------------------------

 - Function: color-name COLOR &optional DOMAIN
     This function returns the name of the COLOR in the specified
     DOMAIN, if any.  COLOR should be a color specifier object and
     DOMAIN is normally a window and defaults to the selected window if
     omitted.  This is equivalent to using `specifier-instance' and
     applying `color-instance-name' to the result.

 - Function: color-rgb-components COLOR &optional DOMAIN
     This function returns the RGB components of the COLOR in the
     specified DOMAIN, if any.  COLOR should be a color specifier
     object and DOMAIN is normally a window and defaults to the
     selected window if omitted.  This is equivalent to using
     `specifier-instance' and applying `color-instance-rgb-components'
     to the result.

          (color-rgb-components (face-background 'default (next-window)))
              => (65535 58596 46517)

Glyphs
******

   A "glyph" is an object that is used for pixmaps and images of all
sorts, as well as for things that "act" like pixmaps, such as
non-textual strings ("annotations") displayed in a buffer or in the
margins.  It is used in begin-glyphs and end-glyphs attached to extents,
marginal and textual annotations, overlay arrows (`overlay-arrow-*'
variables), toolbar buttons, mouse pointers, frame icons, truncation and
continuation markers, and the like. (Basically, any place there is an
image or something that acts like an image, there will be a glyph object
representing it.)

   The actual image that is displayed (as opposed to its position or
clipping) is defined by an "image specifier" object contained within
the glyph.  The separation between an image specifier object and a
glyph object is made because the glyph includes other properties than
just the actual image: e.g. the face it is displayed in (for text
images), the alignment of the image (when it is in a buffer), etc.

 - Function: glyphp OBJECT
     This function returns `t' if OBJECT is a glyph.

Glyph Functions
===============

Creating Glyphs
---------------

 - Function: make-glyph &optional SPEC-LIST TYPE
     This function creates a new glyph object of type TYPE.

     SPEC-LIST is used to initialize the glyph's image.  It is
     typically an image instantiator (a string or a vector; see Image Specifiers),
     but can also be a list of such instantiators (each
     one in turn is tried until an image is successfully produced), a
     cons of a locale (frame, buffer, etc.) and an instantiator, a list
     of such conses, or any other form accepted by
     `canonicalize-spec-list'.  See Specifiers for more information
     about specifiers.

     TYPE specifies the type of the glyph, which specifies in which
     contexts the glyph can be used, and controls the allowable image
     types into which the glyph's image can be instantiated.  TYPE
     should be one of `buffer' (used for glyphs in an extent, the
     modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
     for the mouse-pointer), or `icon' (used for a frame's icon), and
     defaults to `buffer'.  See Glyph Types.

 - Function: make-glyph-internal &optional TYPE
     This function creates a new, uninitialized glyph of type TYPE.

 - Function: make-pointer-glyph &optional SPEC-LIST
     This function is equivalent to calling `make-glyph' with a TYPE of
     `pointer'.

 - Function: make-icon-glyph &optional SPEC-LIST
     This function is equivalent to calling `make-glyph' with a TYPE of
     `icon'.

Glyph Properties
----------------

   Each glyph has a list of properties, which control all of the
aspects of the glyph's appearance.  The following symbols have
predefined meanings:

`image'
     The image used to display the glyph.

`baseline'
     Percent above baseline that glyph is to be displayed.  Only for
     glyphs displayed inside of a buffer.

`contrib-p'
     Whether the glyph contributes to the height of the line it's on.
     Only for glyphs displayed inside of a buffer.

`face'
     Face of this glyph (*not* a specifier).

 - Function: set-glyph-property GLYPH PROPERTY VALUE &optional LOCALE
          TAG-SET HOW-TO-ADD
     This function changes a property of a GLYPH.

     For built-in properties, the actual value of the property is a
     specifier and you cannot change this; but you can change the
     specifications within the specifier, and that is what this
     function will do.  For user-defined properties, you can use this
     function to either change the actual value of the property or, if
     this value is a specifier, change the specifications within it.

     If PROPERTY is a built-in property, the specifications to be added
     to this property can be supplied in many different ways:

        * If VALUE is a simple instantiator (e.g. a string naming a
          pixmap filename) or a list of instantiators, then the
          instantiator(s) will be added as a specification of the
          property for the given LOCALE (which defaults to `global' if
          omitted).

        * If VALUE is a list of specifications (each of which is a cons
          of a locale and a list of instantiators), then LOCALE must be
          `nil' (it does not make sense to explicitly specify a locale
          in this case), and specifications will be added as given.

        * If VALUE is a specifier (as would be returned by
          `glyph-property' if no LOCALE argument is given), then some
          or all of the specifications in the specifier will be added
          to the property.  In this case, the function is really
          equivalent to `copy-specifier' and LOCALE has the same
          semantics (if it is a particular locale, the specification
          for the locale will be copied; if a locale type,
          specifications for all locales of that type will be copied;
          if `nil' or `all', then all specifications will be copied).

     HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
     `append', `remove-tag-set-prepend', `remove-tag-set-append',
     `remove-locale', `remove-locale-type', or `remove-all'.  See
     `copy-specifier' and `add-spec-to-specifier' for a description of
     what each of these means.  Most of the time, you do not need to
     worry about this argument; the default behavior usually is fine.

     In general, it is OK to pass an instance object (e.g. as returned
     by `glyph-property-instance') as an instantiator in place of an
     actual instantiator.  In such a case, the instantiator used to
     create that instance object will be used (for example, if you set
     a font-instance object as the value of the `font' property, then
     the font name used to create that object will be used instead).
     If some cases, however, doing this conversion does not make sense,
     and this will be noted in the documentation for particular types
     of instance objects.

     If PROPERTY is not a built-in property, then this function will
     simply set its value if LOCALE is `nil'.  However, if LOCALE is
     given, then this function will attempt to add VALUE as the
     instantiator for the given LOCALE, using `add-spec-to-specifier'.
     If the value of the property is not a specifier, it will
     automatically be converted into a `generic' specifier.

 - Function: glyph-property GLYPH PROPERTY &optional LOCALE
     This function returns GLYPH's value of the given PROPERTY.

     If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
     be returned.  For built-in properties, this will be a specifier
     object of a type appropriate to the property (e.g. a font or color
     specifier).  For other properties, this could be anything.

     If LOCALE is supplied, then instead of returning the actual value,
     the specification(s) for the given locale or locale type will be
     returned.  This will only work if the actual value of PROPERTY is
     a specifier (this will always be the case for built-in properties,
     but may or may not apply to user-defined properties).  If the
     actual value of PROPERTY is not a specifier, this value will
     simply be returned regardless of LOCALE.

     The return value will be a list of instantiators (e.g. vectors
     specifying pixmap data), or a list of specifications, each of
     which is a cons of a locale and a list of instantiators.
     Specifically, if LOCALE is a particular locale (a buffer, window,
     frame, device, or `global'), a list of instantiators for that
     locale will be returned.  Otherwise, if LOCALE is a locale type
     (one of the symbols `buffer', `window', `frame', or `device'), the
     specifications for all locales of that type will be returned.
     Finally, if LOCALE is `all', the specifications for all locales of
     all types will be returned.

     The specifications in a specifier determine what the value of
     PROPERTY will be in a particular "domain" or set of circumstances,
     which is typically a particular Emacs window along with the buffer
     it contains and the frame and device it lies within.  The value is
     derived from the instantiator associated with the most specific
     locale (in the order buffer, window, frame, device, and `global')
     that matches the domain in question.  In other words, given a
     domain (i.e. an Emacs window, usually), the specifier for PROPERTY
     will first be searched for a specification whose locale is the
     buffer contained within that window; then for a specification
     whose locale is the window itself; then for a specification whose
     locale is the frame that the window is contained within; etc.  The
     first instantiator that is valid for the domain (usually this
     means that the instantiator is recognized by the device [i.e. the
     X server or TTY device] that the domain is on).  The function
     `glyph-property-instance' actually does all this, and is used to
     determine how to display the glyph.

 - Function: glyph-property-instance GLYPH PROPERTY &optional DOMAIN
          DEFAULT NO-FALLBACK
     This function returns the instance of GLYPH's PROPERTY in the
     specified DOMAIN.

     Under most circumstances, DOMAIN will be a particular window, and
     the returned instance describes how the specified property
     actually is displayed for that window and the particular buffer in
     it.  Note that this may not be the same as how the property
     appears when the buffer is displayed in a different window or
     frame, or how the property appears in the same window if you
     switch to another buffer in that window; and in those cases, the
     returned instance would be different.

     The returned instance is an image-instance object, and you can
     query it using the appropriate image instance functions.  For
     example, you could use `image-instance-depth' to find out the
     depth (number of color planes) of a pixmap displayed in a
     particular window.  The results might be different from the
     results you would get for another window (perhaps the user
     specified a different image for the frame that window is on; or
     perhaps the same image was specified but the window is on a
     different X server, and that X server has different color
     capabilities from this one).

     DOMAIN defaults to the selected window if omitted.

     DOMAIN can be a frame or device, instead of a window.  The value
     returned for such a domain is used in special circumstances when a
     more specific domain does not apply; for example, a frame value
     might be used for coloring a toolbar, which is conceptually
     attached to a frame rather than a particular window.  The value is
     also useful in determining what the value would be for a
     particular window within the frame or device, if it is not
     overridden by a more specific specification.

     If PROPERTY does not name a built-in property, its value will
     simply be returned unless it is a specifier object, in which case
     it will be instanced using `specifier-instance'.

     Optional arguments DEFAULT and NO-FALLBACK are the same as in
     `specifier-instance'.  See Specifiers.

 - Function: remove-glyph-property GLYPH PROPERTY &optional LOCALE
          TAG-SET EXACT-P
     This function removes a property from a glyph.  For built-in
     properties, this is analogous to `remove-specifier'.  See
     remove-specifier-p, for the meaning of the LOCALE,
     TAG-SET, and EXACT-P arguments.

Glyph Convenience Functions
---------------------------

   The following functions are provided for working with specific
properties of a glyph.  Note that these are exactly like calling the
general functions described above and passing in the appropriate value
for PROPERTY.

   Remember that if you want to determine the "value" of a specific
glyph property, you probably want to use the `*-instance' functions.
For example, to determine whether a glyph contributes to its line
height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
latter will return a boolean specifier or a list of specifications, and
you probably aren't concerned with these.)

 - Function: glyph-image GLYPH &optional LOCALE
     This function is equivalent to calling `glyph-property' with a
     property of `image'.  The return value will be an image specifier
     if LOCALE is `nil' or omitted; otherwise, it will be a
     specification or list of specifications.

 - Function: set-glyph-image GLYPH SPEC &optional LOCALE TAG-SET
          HOW-TO-ADD
     This function is equivalent to calling `set-glyph-property' with a
     property of `image'.

 - Function: glyph-image-instance GLYPH &optional DOMAIN DEFAULT
          NO-FALLBACK
     This function returns the instance of GLYPH's image in the given
     DOMAIN, and is equivalent to calling `glyph-property-instance'
     with a property of `image'.  The return value will be an image
     instance.

     Normally DOMAIN will be a window or `nil' (meaning the selected
     window), and an instance object describing how the image appears
     in that particular window and buffer will be returned.

 - Function: glyph-contrib-p GLYPH &optional LOCALE
     This function is equivalent to calling `glyph-property' with a
     property of `contrib-p'.  The return value will be a boolean
     specifier if LOCALE is `nil' or omitted; otherwise, it will be a
     specification or list of specifications.

 - Function: set-glyph-contrib-p GLYPH SPEC &optional LOCALE TAG-SET
          HOW-TO-ADD
     This function is equivalent to calling `set-glyph-property' with a
     property of `contrib-p'.

 - Function: glyph-contrib-p-instance GLYPH &optional DOMAIN DEFAULT
          NO-FALLBACK
     This function returns whether the glyph contributes to its line
     height in the given DOMAIN, and is equivalent to calling
     `glyph-property-instance' with a property of `contrib-p'.  The
     return value will be either `nil' or `t'. (Normally DOMAIN will be
     a window or `nil', meaning the selected window.)

 - Function: glyph-baseline GLYPH &optional LOCALE
     This function is equivalent to calling `glyph-property' with a
     property of `baseline'.  The return value will be a specifier if
     LOCALE is `nil' or omitted; otherwise, it will be a specification
     or list of specifications.

 - Function: set-glyph-baseline GLYPH SPEC &optional LOCALE TAG-SET
          HOW-TO-ADD
     This function is equivalent to calling `set-glyph-property' with a
     property of `baseline'.

 - Function: glyph-baseline-instance GLYPH &optional DOMAIN DEFAULT
          NO-FALLBACK
     This function returns the instance of GLYPH's baseline value in
     the given DOMAIN, and is equivalent to calling
     `glyph-property-instance' with a property of `baseline'.  The
     return value will be an integer or `nil'.

     Normally DOMAIN will be a window or `nil' (meaning the selected
     window), and an instance object describing the baseline value
     appears in that particular window and buffer will be returned.

 - Function: glyph-face GLYPH
     This function returns the face of GLYPH. (Remember, this is not a
     specifier, but a simple property.)

 - Function: set-glyph-face GLYPH FACE
     This function changes the face of GLYPH to FACE.

Glyph Dimensions
----------------

 - Function: glyph-width GLYPH &optional WINDOW
     This function returns the width of GLYPH on WINDOW.  This may not
     be exact as it does not take into account all of the context that
     redisplay will.

 - Function: glyph-ascent GLYPH &optional WINDOW
     This function returns the ascent value of GLYPH on WINDOW.  This
     may not be exact as it does not take into account all of the
     context that redisplay will.

 - Function: glyph-descent GLYPH &optional WINDOW
     This function returns the descent value of GLYPH on WINDOW.  This
     may not be exact as it does not take into account all of the
     context that redisplay will.

 - Function: glyph-height GLYPH &optional WINDOW
     This function returns the height of GLYPH on WINDOW.  (This is
     equivalent to the sum of the ascent and descent values.)  This may
     not be exact as it does not take into account all of the context
     that redisplay will.

Images
======

Image Specifiers
----------------

   An image specifier is used to describe the actual image of a glyph.
It works like other specifiers (see Specifiers.), in that it
contains a number of specifications describing how the image should
appear in a variety of circumstances.  These specifications are called
"image instantiators".  When XEmacs wants to display the image, it
instantiates the image into an "image instance".  Image instances are
their own primitive object type (similar to font instances and color
instances), describing how the image appears in a particular domain.
(On the other hand, image instantiators, which are just descriptions of
how the image should appear, are represented using strings or vectors.)

 - Function: image-specifier-p OBJECT
     This function returns non-`nil' if OBJECT is an image specifier.
     Usually, an image specifier results from calling `glyph-image' on
     a glyph.

 - Function: make-image-specifier SPEC-LIST
     This function creates a new image specifier object and initializes
     it according to SPEC-LIST.  It is unlikely that you will ever want
     to do this, but this function is provided for completeness and for
     experimentation purposes.  See Specifiers.

   Image instantiators come in many formats: `xbm', `xpm', `gif',
`jpeg', etc.  This describes the format of the data describing the
image.  The resulting image instances also come in many types -
`mono-pixmap', `color-pixmap', `text', `pointer', etc.  This refers to
the behavior of the image and the sorts of places it can appear. (For
example, a color-pixmap image has fixed colors specified for it, while
a mono-pixmap image comes in two unspecified shades "foreground" and
"background" that are determined from the face of the glyph or
surrounding text; a text image appears as a string of text and has an
unspecified foreground, background, and font; a pointer image behaves
like a mono-pixmap image but can only be used as a mouse pointer
[mono-pixmap images cannot be used as mouse pointers]; etc.) It is
important to keep the distinction between image instantiator format and
image instance type in mind.  Typically, a given image instantiator
format can result in many different image instance types (for example,
`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
whereas `cursor-font' can be instanced only as `pointer'), and a
particular image instance type can be generated by many different image
instantiator formats (e.g.  `color-pixmap' can be generated by `xpm',
`gif', `jpeg', etc.).

   See Image Instances for a more detailed discussion of image
instance types.

   An image instantiator should be a string or a vector of the form

      `[FORMAT :KEYWORD VALUE ...]'

   i.e. a format symbol followed by zero or more alternating
keyword-value pairs.  The "format" field should be a symbol, one of

`nothing'
     (Don't display anything; no keywords are valid for this.  Can only
     be instanced as `nothing'.)

`string'
     (Display this image as a text string.  Can only be instanced as
     `text', although support for instancing as `mono-pixmap' should be
     added.)

`formatted-string'
     (Display this image as a text string with replaceable fields,
     similar to a modeline format string; not currently implemented.)

`xbm'
     (An X bitmap; only if X support was compiled into this XEmacs.
     Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)

`xpm'
     (An XPM pixmap; only if XPM support was compiled into this XEmacs.
     Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
     XPM is an add-on library for X that was designed to rectify the
     shortcomings of the XBM format.  Most implementations of X include
     the XPM library as a standard part.  If your vendor does not, it
     is highly recommended that you download it and install it.  You
     can get it from the standard XEmacs FTP site, among other places.)

`xface'
     (An X-Face bitmap, used to encode people's faces in e-mail
     messages; only if X-Face support was compiled into this XEmacs.
     Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)

`gif'
     (A GIF87 or GIF89 image; only if GIF support was compiled into this
     XEmacs.  Can be instanced as `color-pixmap'.  Note that XEmacs
     includes GIF decoding functions as a standard part of it, so if
     you have X support, you will normally have GIF support, unless you
     explicitly disable it at configure time.)

`jpeg'
     (A JPEG-format image; only if JPEG support was compiled into this
     XEmacs.  Can be instanced as `color-pixmap'.  If you have the JPEG
     libraries present on your system when XEmacs is built, XEmacs will
     automatically detect this and use them, unless you explicitly
     disable it at configure time.)

`png'
     (A PNG/GIF24 image; only if PNG support was compiled into this
     XEmacs.  Can be instanced as `color-pixmap'.)

`tiff'
     (A TIFF-format image; only if TIFF support was compiled into this
     XEmacs.  Not currently implemented.)

`cursor-font'
     (One of the standard cursor-font names, such as `watch' or
     `right_ptr' under X.  Under X, this is, more specifically, any of
     the standard cursor names from appendix B of the Xlib manual [also
     known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix.  On
     other window systems, the valid names will be specific to the type
     of window system.  Can only be instanced as `pointer'.)

`font'
     (A glyph from a font; i.e. the name of a font, and glyph index
     into it of the form `FONT fontname index [[mask-font] mask-index]'.
     Only if X support was compiled into this XEmacs.  Currently can
     only be instanced as `pointer', although this should probably be
     fixed.)

`subwindow'
     (An embedded X window; not currently implemented.)

`autodetect'
     (XEmacs tries to guess what format the data is in.  If X support
     exists, the data string will be checked to see if it names a
     filename.  If so, and this filename contains XBM or XPM data, the
     appropriate sort of pixmap or pointer will be created. [This
     includes picking up any specified hotspot or associated mask
     file.] Otherwise, if `pointer' is one of the allowable
     image-instance types and the string names a valid cursor-font
     name, the image will be created as a pointer.  Otherwise, the
     image will be displayed as text.  If no X support exists, the
     image will always be displayed as text.)

   The valid keywords are:

`:data'
     (Inline data.  For most formats above, this should be a string.
     For XBM images, this should be a list of three elements: width,
     height, and a string of bit data.  This keyword is not valid for
     instantiator format `nothing'.)

`:file'
     (Data is contained in a file.  The value is the name of this file.
     If both `:data' and `:file' are specified, the image is created
     from what is specified in `:data' and the string in `:file'
     becomes the value of the `image-instance-file-name' function when
     applied to the resulting image-instance.  This keyword is not
     valid for instantiator formats `nothing', `string',
     `formatted-string', `cursor-font', `font', and `autodetect'.)

`:foreground'
`:background'
     (For `xbm', `xface', `cursor-font', and `font'.  These keywords
     allow you to explicitly specify foreground and background colors.
     The argument should be anything acceptable to
     `make-color-instance'.  This will cause what would be a
     `mono-pixmap' to instead be colorized as a two-color color-pixmap,
     and specifies the foreground and/or background colors for a pointer
     instead of black and white.)

`:mask-data'
     (For `xbm' and `xface'.  This specifies a mask to be used with the
     bitmap.  The format is a list of width, height, and bits, like for
     `:data'.)

`:mask-file'
     (For `xbm' and `xface'.  This specifies a file containing the mask
     data.  If neither a mask file nor inline mask data is given for an
     XBM image, and the XBM image comes from a file, XEmacs will look
     for a mask file with the same name as the image file but with
     `Mask' or `msk' appended.  For example, if you specify the XBM file
     `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
     associated mask file `left_ptrmsk' will automatically be picked
     up.)

`:hotspot-x'
`:hotspot-y'
     (For `xbm' and `xface'.  These keywords specify a hotspot if the
     image is instantiated as a `pointer'.  Note that if the XBM image
     file specifies a hotspot, it will automatically be picked up if no
     explicit hotspot is given.)

`:color-symbols'
     (Only for `xpm'.  This specifies an alist that maps strings that
     specify symbolic color names to the actual color to be used for
     that symbolic color (in the form of a string or a color-specifier
     object).  If this is not specified, the contents of
     `xpm-color-symbols' are used to generate the alist.)

   If instead of a vector, the instantiator is a string, it will be
converted into a vector by looking it up according to the specs in the
`console-type-image-conversion-list' for the console type of the domain
(usually a window; sometimes a frame or device) over which the image is
being instantiated.

   If the instantiator specifies data from a file, the data will be
read in at the time that the instantiator is added to the image
specifier (which may be well before the image is actually displayed),
and the instantiator will be converted into one of the inline-data
forms, with the filename retained using a `:file' keyword.  This
implies that the file must exist when the instantiator is added to the
image, but does not need to exist at any other time (e.g. it may safely
be a temporary file).

 - Function: valid-image-instantiator-format-p FORMAT
     This function returns non-`nil' if FORMAT is a valid image
     instantiator format.  Note that the return value for many formats
     listed above depends on whether XEmacs was compiled with support
     for that format.

 - Function: image-instantiator-format-list
     This function return a list of valid image-instantiator formats.

 - Variable: xpm-color-symbols
     This variable holds definitions of logical color-names used when
     reading XPM files.  Elements of this list should be of the form
     `(COLOR-NAME FORM-TO-EVALUATE)'.  The COLOR-NAME should be a
     string, which is the name of the color to define; the
     FORM-TO-EVALUATE should evaluate to a color specifier object, or a
     string to be passed to `make-color-instance' (see Colors.).  If
     a loaded XPM file references a symbolic color called COLOR-NAME,
     it will display as the computed color instead.

     The default value of this variable defines the logical color names
     `"foreground"' and `"background"' to be the colors of the
     `default' face.

 - Variable: x-bitmap-file-path
     A list of the directories in which X bitmap files may be found.
     If nil, this is initialized from the `"*bitmapFilePath"' resource.
     This is used by the `make-image-instance' function (however, note
     that if the environment variable `XBMLANGPATH' is set, it is
     consulted first).

Image Instantiator Conversion
-----------------------------

 - Function: set-console-type-image-conversion-list CONSOLE-TYPE LIST
     This function sets the image-conversion-list for consoles of the
     given CONSOLE-TYPE.  The image-conversion-list specifies how image
     instantiators that are strings should be interpreted.  Each
     element of the list should be a list of two elements (a regular
     expression string and a vector) or a list of three elements (the
     preceding two plus an integer index into the vector).  The string
     is converted to the vector associated with the first matching
     regular expression.  If a vector index is specified, the string
     itself is substituted into that position in the vector.

     Note: The conversion above is applied when the image instantiator
     is added to an image specifier, not when the specifier is actually
     instantiated.  Therefore, changing the image-conversion-list only
     affects newly-added instantiators.  Existing instantiators in
     glyphs and image specifiers will not be affected.

 - Function: console-type-image-conversion-list CONSOLE-TYPE
     This function returns the image-conversion-list for consoles of
     the given CONSOLE-TYPE.

Image Instances
---------------

   Image-instance objects encapsulate the way a particular image
(pixmap, etc.) is displayed on a particular device.

   In most circumstances, you do not need to directly create image
instances; use a glyph instead.  However, it may occasionally be useful
to explicitly create image instances, if you want more control over the
instantiation process.

 - Function: image-instance-p OBJECT
     This function returns non-`nil' if OBJECT is an image instance.

Image Instance Types
....................

   Image instances come in a number of different types.  The type of an
image instance specifies the nature of the image: Whether it is a text
string, a mono pixmap, a color pixmap, etc.

   The valid image instance types are

`nothing'
     Nothing is displayed.

`text'
     Displayed as text.  The foreground and background colors and the
     font of the text are specified independent of the pixmap.
     Typically these attributes will come from the face of the
     surrounding text, unless a face is specified for the glyph in
     which the image appears.

`mono-pixmap'
     Displayed as a mono pixmap (a pixmap with only two colors where the
     foreground and background can be specified independent of the
     pixmap; typically the pixmap assumes the foreground and background
     colors of the text around it, unless a face is specified for the
     glyph in which the image appears).

`color-pixmap'
     Displayed as a color pixmap.

`pointer'
     Used as the mouse pointer for a window.

`subwindow'
     A child window that is treated as an image.  This allows (e.g.)
     another program to be responsible for drawing into the window.
     Not currently implemented.

 - Function: valid-image-instance-type-p TYPE
     This function returns non-`nil' if TYPE is a valid image instance
     type.

 - Function: image-instance-type-list
     This function returns a list of the valid image instance types.

 - Function: image-instance-type IMAGE-INSTANCE
     This function returns the type of the given image instance.  The
     return value will be one of `nothing', `text', `mono-pixmap',
     `color-pixmap', `pointer', or `subwindow'.

 - Function: text-image-instance-p OBJECT
     This function returns non-`nil' if OBJECT is an image instance of
     type `text'.

 - Function: mono-pixmap-image-instance-p OBJECT
     This function returns non-`nil' if OBJECT is an image instance of
     type `mono-pixmap'.

 - Function: color-pixmap-image-instance-p OBJECT
     This function returns non-`nil' if OBJECT is an image instance of
     type `color-pixmap'.

 - Function: pointer-image-instance-p OBJECT
     This function returns non-`nil' if OBJECT is an image instance of
     type `pointer'.

 - Function: subwindow-image-instance-p OBJECT
     This function returns non-`nil' if OBJECT is an image instance of
     type `subwindow'.

 - Function: nothing-image-instance-p OBJECT
     This function returns non-`nil' if OBJECT is an image instance of
     type `nothing'.

Image Instance Functions
........................

 - Function: make-image-instance DATA &optional DEVICE DEST-TYPES
          NO-ERROR
     This function creates a new image-instance object.

     DATA is an image instantiator, which describes the image (see
     Image Specifiers.).

     DEST-TYPES should be a list of allowed image instance types that
     can be generated.  The DEST-TYPES list is unordered.  If multiple
     destination types are possible for a given instantiator, the "most
     natural" type for the instantiator's format is chosen. (For XBM,
     the most natural types are `mono-pixmap', followed by
     `color-pixmap', followed by `pointer'.  For the other normal image
     formats, the most natural types are `color-pixmap', followed by
     `mono-pixmap', followed by `pointer'.  For the string and
     formatted-string formats, the most natural types are `text',
     followed by `mono-pixmap' (not currently implemented), followed by
     `color-pixmap' (not currently implemented).  The other formats can
     only be instantiated as one type. (If you want to control more
     specifically the order of the types into which an image is
     instantiated, just call `make-image-instance' repeatedly until it
     succeeds, passing less and less preferred destination types each
     time.

     If DEST-TYPES is omitted, all possible types are allowed.

     NO-ERROR controls what happens when the image cannot be generated.
     If NIL, an error message is generated.  If T, no messages are
     generated and this function returns NIL.  If anything else, a
     warning message is generated and this function returns NIL.

 - Function: colorize-image-instance IMAGE-INSTANCE FOREGROUND
          BACKGROUND
     This function makes the image instance be displayed in the given
     colors.  Image instances come in two varieties: bitmaps, which are
     1 bit deep which are rendered in the prevailing foreground and
     background colors; and pixmaps, which are of arbitrary depth
     (including 1) and which have the colors explicitly specified.
     This function converts a bitmap to a pixmap.  If the image
     instance was a pixmap already, nothing is done (and `nil' is
     returned).  Otherwise `t' is returned.

 - Function: image-instance-name IMAGE-INSTANCE
     This function returns the name of the given image instance.

 - Function: image-instance-string IMAGE-INSTANCE
     This function returns the string of the given image instance.
     This will only be non-`nil' for text image instances.

 - Function: image-instance-file-name IMAGE-INSTANCE
     This function returns the file name from which IMAGE-INSTANCE was
     read, if known.

 - Function: image-instance-mask-file-name IMAGE-INSTANCE
     This function returns the file name from which IMAGE-INSTANCE's
     mask was read, if known.

 - Function: image-instance-depth IMAGE-INSTANCE
     This function returns the depth of the image instance.  This is 0
     for a mono pixmap, or a positive integer for a color pixmap.

 - Function: image-instance-height IMAGE-INSTANCE
     This function returns the height of the image instance, in pixels.

 - Function: image-instance-width IMAGE-INSTANCE
     This function returns the width of the image instance, in pixels.

 - Function: image-instance-hotspot-x IMAGE-INSTANCE
     This function returns the X coordinate of the image instance's
     hotspot, if known.  This is a point relative to the origin of the
     pixmap.  When an image is used as a mouse pointer, the hotspot is
     the point on the image that sits over the location that the
     pointer points to.  This is, for example, the tip of the arrow or
     the center of the crosshairs.

     This will always be `nil' for a non-pointer image instance.

 - Function: image-instance-hotspot-y IMAGE-INSTANCE
     This function returns the Y coordinate of the image instance's
     hotspot, if known.

 - Function: image-instance-foreground IMAGE-INSTANCE
     This function returns the foreground color of IMAGE-INSTANCE, if
     applicable.  This will be a color instance or `nil'. (It will only
     be non-`nil' for colorized mono pixmaps and for pointers.)

 - Function: image-instance-background IMAGE-INSTANCE
     This function returns the background color of IMAGE-INSTANCE, if
     applicable.  This will be a color instance or `nil'. (It will only
     be non-`nil' for colorized mono pixmaps and for pointers.)